協調記錄: m03.getNextTransferStation() 接口阻塞

問題摘要

問題描述

背景

m01-狀態感知引擎在實現L2提醒觸發邏輯時，需要知道用戶距離下一換乘站的距離和預計到達時間，以決定是否觸發「距離1站提醒」。

阻塞詳情

• @backend-1 在 m01.detectState() 中需要調用 getNextTransferStation()
• 該接口目前未定義文檔，也未實現
• m01開發因此暫停

架構分析

職責歸屬分析

決策：方案A - 由m03提供

理由: 1. 單一職責: 地圖數據和路線計算應集中管理 2. 數據一致性: m03已有OD矩陣和路線數據 3. 可複用性: m02提醒服務未來可能也需要此接口 4. 性能優化: m03可緩存熱門路線計算結果

接口定義（架構師確認版）

接口規範

service: LocationService
method: getNextTransferStation
provider: m03
consumer: m01, m02
version: "1.0.0"

請求/響應

Request:

{
  userId: string;           // 用戶ID
  currentLocation: {
    lat: number;           // 緯度
    lng: number;           // 經度
    accuracy: number;      // GPS精度（米）
  };
  route?: {                // 可選：已知路線信息
    lineId?: string;       // 路線ID
    direction?: number;    // 方向
  };
  context?: {
    speed: number;         // 當前速度（km/h）
    timestamp: number;     // 時間戳
  };
}

Response:

{
  // 下一換乘站信息
  nextStation: {
    id: string;            // 站點ID
    name: string;          // 站點名稱
    nameEn?: string;       // 英文名稱
    location: {
      lat: number;
      lng: number;
    };
    type: "metro" | "bus" | "train";
  };

  // 距離信息
  distance: {
    meters: number;        // 直線距離（米）
    routeMeters?: number;  // 路線距離（米，可選）
    stations: number;      // 剩余站數
  };

  // 預計到達
  eta: {
    seconds: number;       // 預計秒數
    confidence: number;    // 置信度 0-1
  };

  // 提醒觸發建議（供m01參考）
  alertTrigger: {
    shouldAlert: boolean;  // 是否應該觸發提醒
    reason: "approaching" | "arriving" | "none";
    urgency: "low" | "medium" | "high";
  };

  // 元數據
  meta: {
    calculatedAt: number;  // 計算時間戳
    cacheHit: boolean;     // 是否命中緩存
    dataVersion: string;   // 地圖數據版本
  };
}

Error Codes:

{
  "M03_E001": "無法定位到有效路線",
  "M03_E002": "地圖數據缺失",
  "M03_E003": "計算超時",
  "M03_E004": "位置精度不足"
}

行動計劃

Phase 1: 文檔交付（截止時間: 16:00）

Phase 2: 實現交付（預計）

兜底方案（超時觸發）

觸發條件

如 2026-03-08 16:00 前 @backend-2 未完成文檔，則啟動兜底方案

方案B: m01臨時實現

實現方式:

// m01 臨時降級方案
class TemporaryStationCalculator {
  // 使用簡化算法估算
  // 1. 查詢最近的已知站點（緩存）
  // 2. 基於速度和方向粗略估計
  // 3. 精度降低，但不阻塞主流程

  async getNextTransferStationFallback(
    userId: string,
    location: LatLng
  ): Promise<StationInfo | null> {
    // 簡化實現
  }
}

權衡: - ✅ m01開發不阻塞 - ✅ 可快速上線測試 - ❌ 精度較低（約70%準確率） - ❌ 無法處理複雜換乘場景 - ❌ 技術債：需後續遷移到m03

檢查清單

架構師跟進項

• [x] 確認職責歸屬
• [x] 定義接口規範
• [ ] 14:00 檢查 @backend-2 響應
• [ ] 16:00 檢查文檔交付
• [ ] 超時後決定是否啟動兜底方案

m03 (@backend-2) 交付項

• [ ] 確認排期響應
• [ ] 接口文檔 (docs/03-interface.md)
• [ ] 數據模型更新
• [ ] 外部地圖API調研

m01 (@backend-1) 準備項

• [ ] 閱讀確認接口定義
• [ ] 準備Mock測試用例
• [ ] 預留兜底方案接入點

溝通記錄

2026-03-08 12:00

@backend-1 → @architect-lead:

發現阻塞：我需要調用 getNextTransferStation() 來判斷L2提醒時機，但m03沒有這個接口。請協調。

2026-03-08 12:30

@architect-lead → @backend-1, @backend-2:

已確認該接口應由m03提供。接口定義見上文。 @backend-2 請確認是否可在16:00前交付文檔？如有困難請及時反饋。

🐿️ 松鼠提醒項目 | 架構師 @architect-lead

正在協調 m03 接口阻塞問題

• 已確認接口歸屬：m03
• 已定義接口規範（見上文）
• 檢查時間：14:00, 16:00
• 兜底方案：m01臨時實現（精度降級）